home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga Plus 1995 #1
/
Amiga Plus 1995 #1.iso
/
fish-disketten
/
fish_941-950
/
d948
/
snoopy
/
ini
/
ini.doc
< prev
next >
Wrap
Text File
|
1994-12-13
|
33KB
|
928 lines
TABLE OF CONTENTS
ini.library/--background--
ini.library/ini_ChangeString
ini.library/ini_CheckProtection
ini.library/ini_Delete
ini.library/ini_DeleteFilename
ini.library/ini_ErrorString
ini.library/ini_GetBool
ini.library/ini_GetHeader
ini.library/ini_GetInteger
ini.library/ini_GetString
ini.library/ini_GetVariable
ini.library/ini_LocalConfig
ini.library/ini_New
ini.library/ini_NewConfig
ini.library/ini_NewFilename
ini.library/ini_OpenFile
ini.library/ini_ProtectSection
ini.library/ini_RemoveVariable
ini.library/ini_Save
ini.library/--background-- ini.library/--background--
PURPOSE
The ini.library was written to give the amiga user a more consistent
configuration file format, and programmers a much easier way of
storing config or project information on disks.
Most programs have config files to store global settings and such.
These files have all different structures people in the real world
(the users) cannot examine or understand; and, worse yet, often differ
from version to version. We all know the hassle with those 'old->new'
configuration file converters...With the ini.library this changes: you
have access to a standardized ini file format known from other
operating systems such as unix, windows and so on; it allows
you to save your config stuff much easier (less code), and it
enables the user to read and even modify configuration data with
a simple text editor (or, a wide-range field for unemployed PD
programmers: using an INI editor)
As the ini.library is I-WANT-TO-BE-FREE-WARE you are ENCOURAGED to
use it - its free of charge! (go ahead, do it!) and it offers much
more comfort to your applications. PD dealers, diskmags, everyone,
I'd like you to push'n'hype the ini.library ;-).
INI files are plain line-oriented ASCII texts that can contain three
possible types of lines : COMMENTS, HEADERS and VARIABLES. COMMENTS are
lines that include additional information not used by the parser.
You can use these comment lines to give the user ideas about what
your variables mean and what reasonable changes s(he) is allowed
to make to that variables. HEADERS are identifiers for sections and
are enclosed in [] brackets. A SECTION is a group of zero to infinite (?)
number of variables and provides a simple but efficient means of
logically grouping data. VARIABLES are simple statements in the
form "<variable>=<contents>" where both <variable> and <contents>
could be virtually anything - you name it.
Each INI file must start with a sequence of 4 characters ";INI"
otherwise the ini.library will return the INIERROR_INVALID_INI_FILE.
This was included to prevent misuse of the ini.library: imagine your
program has a 'load user configuration' menu and the user tries out
some binary hack or an IFF picture (you know users, don't you?! ;-)
If you watch out for INIERROR_INVALID_INI_FILE, you can send the user
a message of complaint and ignore its wishes -> great.
Since this is a cause for many first-time problems, from version 2.1
upwards this checking can be made optional; see ini_NewConfig() for
details
COMMENTS
Comments can be placed anywhere [well, almost]. If you want
to have a full-line comment, place a ';' or a '*' in the first
column of that line. Anything after these two characters will be ignored.
If you want to place a comment at the end of a line you should use
the ';' sign ONLY. Also note that if you make a comment after a
variable you should probably enclose its contents in quotation marks;
otherwise the whitespaces between the last character of the contents
and the comment start will be part of the contents. This is
no problem if you are using integer or boolean variables; it might
be a problem for SOME string variables, but doesn't necessarily have
to - its up to your interpretation of the input data.
Examples:
;INI for MUIMon release version
* another piece of wisdom
best part of munich=ULTRAWORLD ; 100% wild techno
SECTIONS
Sections are used to group variables logically. You should try to place
all your data in groups so that your inifiles have a more consistent
look and both you and the user can find data easier. The concept of
sections can have various usages, one is to handle logic groupings
for one program, another is to handle data related to different
programs accessing the same INI file, yet another is to just make
your INI more readable. Of course,the ini.library is flexible enough
to ignore sections altogether, but you shouldn't force it! Sections
cost you nothing and make for a lot better programs.
HEADERS
Headers start a new section. Headers are strings enclosed in
[] brackets and can be any string you like. Everything following
a header is logically assigned to that header - up to the next
section header or an end-of-file.
Examples:
[drivers]
pc0=storage:dosdrivers/pc0
cd=devs:CDROM
[Disko Lovers,International]
best ULTRAWORLD DJs=MONIKA,TIN-A-303,BLEEP & TRIPPLE R,DJ HELL
; hi to SMC all ravers around the globe. See you on MAYDAY V
[hermeneutic philosophy revisited]
zizek=no meta language exists
VARIABLES
Variables are basically strings that are assigned a name. The
names is what you search for, the strings is what you get -it is as
simple as that. For instance, in "TABS=8" the string "TABS" is
the name (also called the variable), the string "8" is its value.
The interpretation of the string value is up to you. The ini.library
provides three basic types of interpretation : Strings, Integers (LONGs)
and boolean Values (BOOLs). You can of course add your own
interpretations as you like, and this is why the ini concept is so
flexible: You can virtually store ALL information you need in such
a way that it is represented as an ASCII string. If you want your
strings to be of a certain length, you can enclose them in
brackets, for example such as in
user="T\"N\"I and THE DREAM TEAM"
where you can assign the string >T"N"I AND THE DREAM TEAM< to
the variable named >user<. Note that a sequence of \" is used
as an escape character in the above example.
If you have ideas for additional datatypes of general interest
the ini.library should understand, please contact me. If possible,
I'll include them.
Examples:
--------------------------------------------------------------
;INI
[GLOBAL]
user="T'N'I and The Dream Team" ;from INTENSE Records
tabs=8
indent=YES
autofold=FALSE
preferences=
[DIRECTORYS]
home=work:assembler/
; add multiple directorys by using '+' or ','
include=include:+dh1:more_includes/
libs=dh2:code/libs/asm/+lib:+disko:love
--------------------------------------------------------------
The above example shows you some ideas of inifiles: Two groups
are part of this inifile: GLOBAL and DIRECTORYS. Each section
can (but doesn't have to) have different variables, each variable
can be any string enclosed in quotation marks or from the = sign
to the end of the line. If you want to add comments, enclose the
string in quotes, and add a comment like in the "user=" line above.
Note that the feature described as "add multiple directorys by ..."
is a description of an add-on datatype used by the application for
this INI file and NOT provided by the ini.library itself.
Now you should be able to read inifiles. More complex features such
as section protection and file location are described in the
"programmers.guide" document which should be part of this distribution.
HINTS
If you decide to use the ini.library -WHICH I STRONGLY HOPE YOU DO-
you should always check for error returns - you may never know when
they come in handy for you.
If you save your files, make use of the grouping feature; that is,
at least provide some GLOBAL section so that the user knows what
he's up for. It makes INIfiles more readable and doesn't cost
you anything.
LIMITATIONS
Yes, there are some.
* currently no whitespaces before and after the "=" are allowed.
This means that the two following lines are different for
the ini.library parser functions
ultraworld=great
ultraworld = great
There is a simple workaround for this: just do your own variable
and contents parsing (explicit datatypes, see above). Future
versions WILL include a fix on that, I PROMISE.
* the ini.library uses approximately twice as much memory as the
ini file is in size (less for larger files). This is not a
problem for most users, because inifiles seldom grow over
a size of some 10-20 kb (even on windows I haven't seen a inifile
larger than 25kb up to this day), and many applications not even
reach a 5kb limit. (You can write a LOT variables in a 5 kb file).
However, this memory is needed only while your parser is active,
(i.e. between calls to ini_New() and ini_Delete() ). Afterwards,
only the library code (5kb) is kept in memory.
ini.library/ini_ChangeString ini.library/ini_ChangeString
NAME
ini_ChangeString -- change an existing string for a variable
SYNOPSIS
error = ini_ChangeString( parser, header, variable, value )
d0 A0 A1 A2 A3
INIERROR ini_ChangeString(INIPARSER *,STRPTR,STRPTR,STRPTR);
FUNCTION
Changes the contents of a variable to a new value. If you have
made changes to the data represented in an inifile (e.g. your
internal configuration structure) you can use this function
to fix those changes and then write back your file with ini_Save().
If the variable already existed, its contents will be replaced by
the new contents; if it didn't exist, it will be appended to the
section it is assigned to. Unless you use explicit saving of
ini-files you *MUST* use ini_ChangeString() to change the
contents of variables, **NEVER** try to do it on your own
(its quite tricky, actually!).
INPUTS
parser - pointer to a valid INIPARSER
header - section header name
variable - section variable name
value - new contents
RESULTS
error - INIERROR as defined in libraries/ini.h
NOTE
old end-of-line comments will be stripped by this function. You can
explicitly set one by using contents such as
char *newContents = "\"blabla\" ;comment "; or
dc.b '"blabla" ;comment',0
SEE ALSO
ini_RemoveVariable, ini_Save
ini.library/ini_CheckProtection ini.library/ini_CheckProtection
NAME
ini_CheckProtection -- check if a section has a valid protection
SYNOPSIS
error = ini_CheckProtection( header, password )
d0 A0 A1
INIERROR ini_CheckProtection( INILINEINFO *, STRPTR )
FUNCTION
This function checks if it can find a "$code" variable in the given
section and if that code matches the password given as an argument.
The password is case sensitive and must match *EXACTLY* the one used
to code that particular section (including whitespaces and so on).
It is up the caller to decide what to do if a section is not
properly coded : you can make it a fatal problem or just ignore
it - whatever you like. This means, the ini.library will load files
with or without invalid passwords - YOU have the "power" to handle
this situation (actually, this was done because it is not a feature
of the normal inifile "standard", its a addon bonus of the ini.library)
INPUTS
header - pointer to a INILINEINFO structure for a section header
(i.e. ili_Flags must be INIFLAG_HEADER )
password - pointer to the password (assumably) used to protect this
section
RESULTS
error - INIERROR as defined in libraries/ini.h; you should look out
for INIERROR_NONE = good, INIERROR_INVALID_PASSWORD = bad
SEE ALSO
ini_ProtectSection
ini.library/ini_Delete ini.library/ini_Delete
NAME
ini_Delete -- delete INI parser
SYNOPSIS
error = ini_Delete( parser )
D0 A0
INIERROR ini_Delete( INIPARSER * );
FUNCTION
Free all memory used by an INI parser and reset all accompaning
internal data structures. You should ALWAYS call this function
after you have finished using the INI file so that you don't loose
any precious memory. You must call ini_Delete() even if ini_New()
wasn't able to create the parser for you (there still might be
some memory somewhere only ini_Delete can take care of)
WARNING
This function does not arbitrate for access to the parser. The
calling task must be the owner of the involved parser.
INPUTS
parser - a pointer to a parser structure initialized with ini_New()
RESULTS
error - INIERROR as defined in libraries/ini.h
SEE ALSO
ini_New
ini.library/ini_DeleteFilename ini.library/ini_DeleteFilename
NAME
ini_DeleteFilename() -- destructor for ini_NewFilename()
SYNOPSIS
ini_DeleteFilename( filename )
D0
void ini_DeleteFilename( STRPTR )
FUNCTION
This function will deallocate memory associated with a filename
generated by ini_NewFilename()
INPUTS
filename - a filename returned from ini_NewFilename
NOTE
after calling ini_DeleteFilename() your "filename" variable is
invalid : DO NOT USE IT ANY LONGER!
RESULTS
none
SEE ALSO
ini_NewFilename()
ini.library/ini_ErrorString ini.library/ini_ErrorString
NAME
ini_ErrorString -- find error message to an INIERROR
SYNOPSIS
message = ini_ErrorString( error )
D0 D0
STRPTR ini_ErrorString( INIERROR )
FUNCTION
Used to find an ini.library error message. Currently the error
strings are in english but a localized version is planed for the
next update of this library, so you should use ini_ErrorString()
when printing warnings instead of your own error strings. Also, if
you use ini_ErrorString() you automagically can handle errors that
result from higher library versions.
INPUTS
error - some INIERROR code returned by one of the ini.library functions
RESULTS
message - the error message for that error code (soon to be localized)
If there was no error message (because of INIERROR_NONE or an
invalid error code) ini_ErrorString() will return an EMPTY
string ( "" ) and not NULL, so you can always do something
like
printf("%s\n", ini_ErrorString( ini_Whatever(...) ) );.
NOTE
You are NOT allowed to modify this string, if you need to do so,
make a copy of the string and use that copy instead.
ini.library/ini_GetBool ini.library/ini_GetBool
NAME
ini_GetBool -- find a boolean variable
SYNOPSIS
error = ini_GetBool(parser,head,var,defaultBool,target)
d0 A0 A1 A2 D0 A3
INIERROR ini_GetBool(INIPARSER *,STRPTR,STRPTR,BOOL,BOOL *);
FUNCTION
Used to find a boolean in an inifile. If the value cannot be found
for any reason, a default value is used. The variable should be
"YES",
"Y",
"ON" or
"ACTIVE"
if the returned value is to be TRUE, otherwise FALSE will be returned.
Future Versions of the ini.library will probably include locale-dependant
IDs in addition to those above. You can use ini_GetBool() very good to
handle boolean flags in your configuration - and it is a lot more
readable than other solutions.
INPUTS
parser - pointer to an INIPARSER opened by ini_New()
head - section header name
var - section variable name
defaultBool - default value if boolean value not found
target - adress of target Bool
RESULTS
error - INIERROR as defined in libraries/ini.h. Actually, you can
normally ignore this error code, because you must provide a
default value anyway.
SEE ALSO
ini_GetInteger, ini_GetString
ini.library/ini_GetHeader ini.library/ini_GetHeader
NAME
ini_GetHeader -- find a section header
SYNOPSIS
header = ini_GetHeader( parser, headerString )
D0 A0 A1
INILINEINFO *ini_GetHeader( INIPARSER *, STRPTR )
FUNCTION
This function is used to locate a section in an INI file by looking
for the section header. If you are looking for a specific variable,
ini_GetString() is probably the better choice, but you can do your
own parsing of INI sections, e.g. if you have 'intelligent' sections;
that is sections with flexible concepts or whatever. You could use
ini_GetVariable() in that case.
INPUTS
parser - a pointer to a parser structure initialized with ini_New()
headerString - name of the section header you are looking for, without
enclosing brackets (ie. "global" )
RESULTS
header - pointer to an INILINEINFO or NULL if that header could not
be found. This can be the case either if the INI file does not
include that particular section, or (worse) the INI parser
wasn't able to complete its job (as you know, all ini.library
functions are save to use). If this is NON-NULL, you can use
it as an argument to ini_GetVariable() or you can do your own
section looping (see "advanced concepts" in the "programmers guide")
SEE ALSO
ini_GetVariable, ini_GetString, ini_New
ini.library/ini_GetInteger ini.library/ini_GetInteger
NAME
ini_GetInteger -- find a long integer variable
SYNOPSIS
error = ini_GetInteger(parser,head,var,defaultLong,target)
d0 A0 A1 A2 D0 A3
INIERROR ini_GetString(INIPARSER *,STRPTR,STRPTR,LONG,LONG *);
FUNCTION
Used to find an integer in an inifile. If the integer cannot be found
for any reason, a default value is used. The ini section should
contain a string representing a long decimal value. If the string
starts with a $ sign, a hexadecimal value is expected, % indicates
binary digits and finally @ sets an octal number. Therefor, the
following four entries will all return the same number
decimal=123
octal=@173
binary=%1111011
hex=$7B
The prefixes are compatible to most assemblers (now you know which
language the ini.library was written in ;-) but a future update
will probably include C-style prefixes (0x and so on).
INPUTS
parser - pointer to an INIPARSER opened by ini_New()
head - section header name
var - section variable name
defaultLong - default value if integer not found
target - adress of target long
RESULTS
error - INIERROR as defined in libraries/ini.h. Actually, you can
normally ignore this error code, because you must provide a
default value anyway.
SEE ALSO
ini_GetBool, ini_GetString
ini.library/ini_GetString ini.library/ini_GetString
NAME
ini_GetString -- find a string variable
SYNOPSIS
error = ini_GetString(parser,head,var,defaultStr,target,sizeOfTarget)
D0 A0 A1 A2 A3 D0 A4
INIERROR ini_GetString(INIPARSER *,STRPTR,STRPTR,STRPTR,STRPTR,WORD);
FUNCTION
Used to find a string in an inifile. If the string cannot be found
for any reason, a default string is used; so unless you desperately
rely on a string to exist as part of an inifile, you can call this
function without even checking for error returns. You can add a
series of ini_GetString() statements for all strings you need to
check without having to worry if they exist or not.
INPUTS
parser - pointer to an INIPARSER opened by ini_New()
head - section header name
var - section variable name
defaultStr - default string to use (NULL is possible)
target - target string
sizeOfTarget - size of target string. ini_GetString() promises
not to overwrite its bounds AND to keep a zero byte at the
end, so actually a maximum of (sizeOfTarget-1) characters
will be written.
RESULTS
error - INIERROR as defined in libraries/ini.h. Actually, you can
normally ignore this error code, because you must provide a
default value anyway.
SEE ALSO
ini_GetBool, ini_GetInteger
ini.library/ini_GetVariable ini.library/ini_GetVariable
NAME
ini_GetVariable -- find a section variable
SYNOPSIS
variable = ini_GetVariable( header, variableName )
D0 A0 A1
INILINEINFO *ini_GetVariable( INILINEINFO *, STRPTR )
FUNCTION
This function is used to locate a variable following a given header
(or, for that matter, any given INILINEINFO). You can use this function
if you want to manually parse a section, if you want to find out if
there are more variables of a given name following a specific variable,
or for anything else you could think of. Note that you cannot pass
the INIPARSER as function arguments, use (parser->table.ln_Head) if
you have to do so.
INPUTS
parser - a pointer to an INILINEINFO structure (from your INIPARSER.table)
or -preferably- as returned by ini_GetHeader()
varibaleString - name of the variable you are looking for, without
enclosing brackets and "=" (ie. "variable" )
RESULTS
variable - pointer to an INILINEINFO or NULL if that variable could not
be found. This can be the case either if the INI file does not
include that particular section, or (worse) the INI parser
wasn't able to complete its job (as you know, all ini.library
functions are save to use).
NOTE
ini_GetVariable() doesn't promise the variable to be a member of
the section you specified with your header. For example,
head = ini_GetHeader( parser, "HEAD ONE" );
info = ini_GetVariable( head, "VARIABLE" );
would find the "VARIABLE=FOUND" entry in the "HEAD TWO" section
if the inifile looked something like this :
[HEAD ONE]
size=3551
[HEAD TWO]
VARIABLE=FOUND
This is A FEATURE, NOT A BUG ;-), yes, because you normally will
use ini_GetVariable() to loop through the complete inifile.
SEE ALSO
ini_GetVariable, ini_GetString, ini_New, ini_ParseSection
ini.library/ini_LocalConfig ini.library/ini_LocalConfig
NAME
ini_LocalConfig() -- get the local configuration
SYNOPSIS
config = ini_LocalConfig()
INICONFIG *ini_LocalConfig( void )
FUNCTION
This function will return the local configuration if one is
defined for the current task. Local configurations are "task
sensitive", which means that one task can have one local config.
ini_LocalConfig() will NOT fall back to the global config, so
if you want to read the current config you would probably write
something like
if( ( config = ini_LocalConfig() ) == NULL )
config = IniBase->GlobalConfig;
INPUTS
none
RESULTS
config - local configuration or NULL if none exists
SEE ALSO
ini_NewConfig(), ini_DeleteConfig()
ini.library/ini_New ini.library/ini_New
NAME
ini_New -- open INI parser
SYNOPSIS
error = ini_New( fileName, parser )
D0 A0 A1
INIERROR ini_New( STRPTR, INIPARSER * );
FUNCTION
Open an inifile and parse its contents. After successfully calling
an inifile with this function you can examine its contents using
the functions provided (eg.ini_GetString()) or manually. You must
call this function before calls to any other ini.library functions.
Don't even think about creating an INIPARSER yourself.
WARNING
This function does not arbitrate for access to the parser. The
calling task must be the owner of the involved parser. Use semaphores
if you want to share parser information with other tasks.
You should always call ini_Delete() on the parser EVEN IF ini_New()
failed. Otherwise some internal memory might get lost somewhere
INPUTS
fileName - name of the input file. This is currently a plain filename
with or without pathname; however you should try to use only
plain filenames ("test.ini" instead of "dh1:somewhere/test.ini")
so that the ini.library can fix inifiles to S:, INI: or whereever
the user wants them located. See "locating files" in the
"programmers guide" for details.
parser - pointer to an empty INIPARSER structure. C programmers simply
add the adress of an INIPARSER variable, ASM programmers
can use a (DS.B ip_SIZEOF) statement (See example TEST.ASM)
RESULTS
error - INIERROR as defined in libraries/ini.h. Proceed ONLY if
error = INIERROR_NONE, else you can forget about it.
SEE ALSO
ini_Delete
ini.library/ini_NewConfig ini.library/ini_NewConfig
NAME
ini_NewConfig() -- setup a local configuration
SYNOPSIS
error = ini_LocalConfig( tagList )
d0 A0
INIERROR ini_LocalConfig( struct TagItem * )
FUNCTION
This function creates a local configuration for your program.
If one already exists it will be modified to use the new values.
See "ini.introduction" for more details on the concept of local
and global ini.library configurations
NOTE
Sorry, no vararg-stub for C-programmers (yet?); I didn't want
to have to write a linklib for only one function...
INPUTS
tagList - a list of tag items. Currently defined tags are :
ICFG_ENABLE_S
ti_Data is BOOL, default = TRUE
ICFG_ENABLE_INI
ti_Data is BOOL default = TRUE
ICFG_ENABLE_ENV
ti_Data is BOOL, default = TRUE
ICFG_ENABLE_USER
ti_Data is BOOL, default = TRUE
ICFG_INIMASK
ti_Data is BOOL, default = FALSE. If set to TRUE, the
ini.library no longer requires the ";INI" at the start
of an input file.
ICFG_ASSIGN
user-assign directory, ti_Data is STRPTR to a
static memory! (i.e. the ini.library will not copy
name name of the user-assign so you MUST keep it in
memory yourself!!!!!! this may change for future releases
but right now its a requirement)
RESULTS
error - INIERROR as defined in libraries/ini.h;
SEE ALSO
ini_LocalConfig(), ini_DeleteConfig()
ini.library/ini_NewFilename ini.library/ini_NewFilename
NAME
ini_NewFilename -- build a config-sensitive INI filename
SYNOPSIS
newname = ini_NewFilename( filename )
d0 A0
STRPTR ini_NewFilename( STRPTR )
FUNCTION
This function builds a complete path+filename for a simple filename
based upon the local (or global) configuration. The problem is simple:
a file named "application.ini" could be located in S:, in INI:, in ENV:,
in a user-defined directory or the current directory. BASED UPON THE
CURRENT CONFIGURATION this function will build a correct filename
for you. Example:
ini_NewFilename( "application.ini" )
could return
"s:application.ini"
"ini:application.ini"
"env:application.ini"
"<user>:application.ini" or just
"application.ini"
You must call ini_DeleteFilename() on a filename returned by this
function.
INPUTS
filename - the basic filename; should NOT contain any path information
(except for subdirectorys: if you are using multiple INIs grouped in
a subdirectory (i.e. "tool/users.ini" -> "ini:tool/users.ini" ))
RESULTS
newname - path + filename, or NULL for OUT_OF_MEMORY error
SEE ALSO
ini_DeleteFilename()
ini.library/ini_OpenFile ini.library/ini_OpenFile
NAME
ini_OpenFile() - open an INI-file
SYNOPSIS
file = ini_OpenFile( filename, mode, parser )
d0 d1 d2 a0
BPTR ini_OpenFile(STRPTR,WORD,INIPARSER *);
FUNCTION
This function opens an INI-File just like dos/Open() would do. However,
it does a little bit more: if you use it in MODE_NEWFILE and have a
valid parser structure, ini_OpenFile() will open the file in that directory
where the original parser was located. The problem is this: because
your program doesn't know where the INI file was loaded from (it could
be INI:, it could be S:, it could be anywhere in the known galaxy)
you wouldn't normally know where to save it back to (unless of course
you don't need explicit saving and use ini_Save() instead of all the fuss).
INPUTS
filename - filename without path or anything
mode - just like dos/Open(), MODE_NEWFILE, MODE_OLDFILE etc.
parser - parser structure. Because the parser has to be initialized, this
probably restricts use of ini_OpenFile() for the general public
to the situation described above: explicitly saving an ini-file
RESULTS
file - just like dos/Open() a pointer to a filehandle you can Read() or
Write() to (or whatever). You must Close() it yourself!
ini.library/ini_ProtectSection ini.library/ini_ProtectSection
NAME
ini_ProtectSection -- protect an INI file section
SYNOPSIS
error = ini_ProtectSection( parser, header, password )
d0 A0 A1 A2
INIERROR ini_ProtectSection( INIPARSER *, INILINEINFO *, STRPTR )
FUNCTION
This function protects a INI file section by adding a new (or updating
an existing) "$code" variable to contain a coded value. The coding
mechanism uses all data given in variables of a section plus a
special password known only to the caller of ini_ProtectSection.
Thus, if a user a) changes contents of variables or b) tries to use
this function with an invalid password the "$code" variable will
become invalid. You can use ini_CheckProtection to see if the
"$code" variable is valid, so there you have your protection mechanism!
In general, if you intend to protect a section, you should do the
following :
* call ini_CheckProtection() : if the section is invalid, send
some error message (or do-what-you-like)
* edit the protected section
* call ini_ProtectSection()
* call ini_Save()
Of course, you should probably skip ini_CheckProtection() during the
development of your application, since you may find the need to quickly
change var contents while debugging and so on. Once working you can use
protected sections to contain "read-only" data you still want to make
public (such as for debugging purposes, or for pure fun, or for making
people jealous and encouraging hackers to take a deeper look at your code)
The concept for protected sections is an add-on to the INI standard
made by the ini.library so you shouldn't expect it to work if you
port code to other OS such as Windows.
NOTE
The password is case sensitive and must match EXACTLY for calls
to ini_ProtectSection()/ini_CheckProtection(); i.e.
"ultraworld" != "Ultraworld" != "ultraworld "
^ ^
INPUTS
parser - pointer to the INIPARSER structure
header - pointer to a INILINEINFO structure for a section header
(i.e. ili_Flags must be INIFLAG_HEADER )
password - pointer to the password you want to use for protection
RESULTS
error - INIERROR as defined in libraries/ini.h; you should look out
for INIERROR_NONE = good, INIERROR_INVALID_PASSWORD = bad
SEE ALSO
ini_CheckProtection
ini.library/ini_RemoveVariable ini.library/ini_RemoveVariable
NAME
ini_RemoveVariable() -- remove an existing variable
SYNOPSIS
error = ini_RemoveVariable( parser, header, variable )
d0 A0 A1 A2
INIERROR ini_RemoveVariable( INIPARSER *,STRPTR,STRPTR );
FUNCTION
This function removes an existing variable from an INIPARSER.
You can use this if you don't need a particular variable anymore;
however you don't have to kill unused variables, because they are
ignored anyway based upon your read requests. DON'T ever remove
a variable manually.
INPUTS
parser - pointer to an INIPARSER
header - section header name
variable - section variable name
RESULTS
error - INIERROR as defined in libraries/ini.h
SEE ALSO
ini_Save, ini_ChangeString
ini.library/ini_Save ini.library/ini_Save
NAME
ini_Save -- save an inifile back to disk
SYNOPSIS
error = ini_Save( fileName, parser )
d0 A0 A1
INIERROR ini_Save( STRPTR, INIPARSER * )
FUNCTION
Save a parser structure back to an inifile. If you have made
changes to an INIPARSER (e.g. by calling ini_ChangeString()), you
can save the complete inifile to disk using this function. If you
have to make lots of changes on the input data, for example if you
save project file information there, you could explicitly save
the file yourself: open it using ini_OpenFile(..,MODE_NEWFILE,..),
then dos/FPrintf() all the contents and finally dos/Close() it.
You have to decide yourself what you prefer; making changes with
ini_ChangeString() and ini_Save() makes more readable code and is
a lot saver (and preserves any comments the user has made); exporting
your internal data as inifiles is probably more straight-forward but
not quite as bullet-proof. Whatever.
INPUTS
fileName - name of inifile to create. No checking is done if
the file already exists; so you must make some provision
for this yourself if you think this could be important.
parser - pointer to an INIPARSER to write back to disk
RESULTS
error - INIERROR as defined in libraries/ini.h
SEE ALSO
ini_ChangeString, ini_RemoveVariable